9.6 Adding Attachments

MH-E has the capability to create multimedia messages. It uses the mime (Multipurpose Internet Mail Extensions) protocol¹ The mime protocol allows you to incorporate images, sound, video, binary files, and even commands that fetch a file with ‘ftp’ when your recipient reads the message!

If you were to create a multimedia message with plain MH commands, you would insert mhbuild or mhn directives (henceforth called MH-style directives into your draft and use the mhbuild command in nmh or mhn command in MH and GNU mailutils to expand them. MH-E works in much the same way, although it provides a handful of commands prefixed with C-c C-m to insert the directives so you don't need to remember the syntax of them. Remember: you can always add MH-style directives by hand².

In addition to MH-style directives, MH-E also supports MML (mime Meta Language) tags³. The option mh-compose-insertion can be used to choose between them. By default, this option is set to ‘MML’ if it is supported since it provides a lot more functionality. This option can also be set to ‘MH’ if MH-style directives are preferred.

The MH-E mime commands require a media type for each body part or attachment. For example, a PDF document is of type ‘application/pdf’ and an HTML document is of type ‘text/html’. Some commands fill in the media type for you, whereas others require you to enter one.

In the cases where MH-E can do so, it will determine the media type automatically. It uses the file command to do this. Failing that, the Emacs function mailcap-mime-types is used to provide a list from which to choose. This function usually reads the file /etc/mime.types.

Whether the media type is chosen automatically, or you choose it from a list, use the type that seems to match best the file that you are including. In the case of binaries, the media type ‘application/x-executable’ can be useful. If you can't find an appropriate media type, use ‘text/plain’ for text messages and ‘application/octet-stream’ for everything else.

You are also sometimes asked for a content description. This is simply an optional brief phrase, in your own words, that describes the object. If you don't care to enter a content description, just press return and none will be included; however, a reader may skip over multimedia fields unless the content description is compelling.

You can also create your own mime body parts. In the following example, I describe how you can create and edit a ‘text/enriched’ body part to liven up your plain text messages with boldface, underlining, and italics. I include an Emacs function which inserts enriched text tags.

     (defvar enriched-text-types '(("b" . "bold") ("i" . "italic")
                                   ("u" . "underline")
                                   ("s" . "smaller") ("B" . "bigger")
                                   ("f" . "fixed")
                                   ("c" . "center"))
       "Alist of (final-character . tag) choices for add-enriched-text.
     Additional types can be found in RFC 1563.")

     (defun add-enriched-text (begin end)
       "Add enriched text tags around region.
     The tag used comes from the list enriched-text-types and is
     specified by the last keystroke of the command.  When called from Lisp,
     arguments are BEGIN and END."
       (interactive "r")
       ;; Set type to the tag indicated by the last keystroke.
       (let ((type (cdr (assoc (char-to-string (logior last-input-char ?`))
                               enriched-text-types))))
         (save-restriction               ; restores state from narrow-to-region
           (narrow-to-region begin end)      ; narrow view to region
           (goto-char (point-min))           ; move to beginning of text
           (insert "<" type ">")             ; insert beginning tag
           (goto-char (point-max))           ; move to end of text
           (insert "</" type ">"))))         ; insert terminating tag
     Emacs function for entering enriched text

To use the function add-enriched-text, first add it to ~/.emacs and create key bindings for it (see Composing).

Then, in your plain text message, set the mark with C-@ or C-<SPC>, type in the text to be highlighted, and type C-c t b. This adds ‘<bold>’ where you set the mark and adds ‘</bold>’ at the location of your cursor, giving you something like: ‘You should be <bold>very</bold>’.

Before sending this message, use C-c C-m C-m (mh-mml-to-mime)⁴ to add MIME header fields. Then replace ‘text/plain’ with ‘text/enriched’ in the ‘Content-Type:’ header field.

You may also be interested in investigating sgml-mode.

Including Files

Binaries, images, sound, and video can be inserted in your message with the command C-c C-m C-i (mh-compose-insertion). You are prompted for the filename containing the object, the media type if it cannot be determined automatically, and a content description. If you're using MH-style directives, you will also be prompted for additional attributes.

Forwarding Multimedia Messages

Mail may be forwarded with mime using the command C-c C-m C-f (mh-compose-forward). You are prompted for a content description, the name of the folder in which the messages to forward are located, and a range of messages, which defaults to the current message in that folder. See Ranges.

Including an FTP Reference

You can have your message initiate an ftp transfer when the recipient reads the message. To do this, use the command C-c C-m C-g (mh-mh-compose-anon-ftp). You are prompted for the remote host and filename, the media type, and the content description.

Including tar Files

If the remote file is a compressed tar file, you can use C-c C-m C-t (mh-mh-compose-external-compressed-tar). Then, in addition to retrieving the file via anonymous ftp as per the command C-c C-m C-g (mh-mh-compose-anon-ftp), the file will also be uncompressed and untarred. You are prompted for the remote host and filename and the content description.

Including Other External Files

The command C-c C-m C-x (mh-mh-compose-external-type) is a general utility for referencing external files. In fact, all of the other commands that insert tags to access external files call this command. You are prompted for the access type, remote host and filename, and content type. If you provide a prefix argument, you are also prompted for a content description, attributes, parameters, and a comment.

Previewing Multimedia Messages

When you are finished editing a mime message, it might look like this:

     3 t08/24  root               received fax files on Wed Aug 24 11:00:
     4+t08/24  To:wohler          Test<<This is a test message to get the





     --:%%  {+inbox} 4 msgs (1-4)   Bot L4     (MH-Folder Show)---------------
     To: wohler
     cc:
     Subject: Test of MIME
     --------
     Here is the SETI@Home logo:

     <#part type="image/x-xpm" filename="~/lib/images/setiathome.xpm"
     disposition=inline description="SETI@home logo">
     <#/part>
     --:**  {draft}   All L8     (MH-Letter)----------------------------------

Typically, you send a message with attachments just like any other message (see Sending Message).

However, you may take a sneak preview of the mime encoding if you wish by running the command C-c C-m C-m (mh-mml-to-mime). The following screen shows the mime encoding specified by the tags. You can see why mail user agents are usually built to hide these details from the user.

     To: wohler
     cc:
     Subject: Test of MIME
     X-Mailer: MH-E 8.1; nmh 1.1; GNU Emacs 23.1
     MIME-Version: 1.0
     Content-Type: multipart/mixed; boundary="=-=-="
     --------
     --=-=-=

     Here is the SETI@Home logo:


     --=-=-=
     Content-Type: image/x-xpm
     Content-Disposition: inline; filename=setiathome.xpm
     Content-Transfer-Encoding: base64
     Content-Description: SETI@home logo

     LyogWFBNICovCnN0YXRpYyBjaGFyICogc2V0aWF0aG9tZV94cG1bXSA9IHsKIjQ1IDQ1IDc2N
     --:--  {draft}   Top L1     (MH-Letter)----------------------------------

This action can be undone by running C-_ (undo).

If you're using MH-style directives, use C-c C-e (mh-mh-to-mime) instead of C-c C-m C-m. This runs the command mhbuild (mhn) on the message which expands the tags⁵. This action can be undone by running C-c C-m C-u (mh-mh-to-mime-undo), which works by reverting to a backup file. You are prompted to confirm this action, but you can avoid the confirmation by adding an argument (for example, C-u C-c C-m C-u).

If you wish to pass additional arguments to mhbuild (mhn) to affect how it builds your message, use the option mh-mh-to-mime-args. For example, you can build a consistency check into the message by setting mh-mh-to-mime-args to ‘-check’. The recipient of your message can then run ‘mhbuild -check’ on the message—mhbuild (mhn) will complain if the message has been corrupted on the way. The command C-c C-e only consults this option when given a prefix argument (as in C-u C-c C-e).

The hook mh-mh-to-mime-hook is called after the message has been formatted by C-c C-e.